README for FreeTDS 0.62.4
Sunday, 13 June 2004

Notable repairs are logged here; the regular README follows below.  
For further details, see ChangeLog or the mailing list archives.  

ODBC
----
Some memory corruption and leaks corrected.  New raiserror.c unit test. 

All Libraries
-------------

String->datetime conversion (dbconvert, et. al.) of 2-digit year "00"
incorrectly yielded 1900.   It now yields 2000.  

                   =======================================

README for FreeTDS 0.62.3
Friday, 9 April 2004

db-lib
------

Stored procedures would sometimes appear to return extra results sets. 
This stemmed from improper interpretation of the DONE tokens returned by
the server.  The "extra" results appeared first, but lacked the expected
metadata, causing dbbind() to fail or causing the application to believe the
stored procedure had returned no results.  Fixed on 4 April 2004. 

ODBC
----

SQLExecute was not always returning an error, even when one existed.  If a
query batch (or stored procedure) consisted of a SELECT statement followed by
another query or more, SQLExecute would return SQL_SUCCESS if the first
statement succeeded, even if one the successive statements failed.  The ODBC
standard says that SQLExecute() should return either a failed or
success-with-info status.  This has been at least partially remediated; more
testing is needed.  

New application: bsqldb
-----------------------

This application reads queries from standard input and writes results to
standard output, using db-lib.  It takes options similar to sqsh/tsql.  It is
intended as a batch processing tool, and as an example of using db-lib.  Sorry,
no man page yet.  

                   =======================================

README for FreeTDS 0.62.2
Monday, 22 March 2004

ODBC
----

1.  SQLRowCount() often returned an error, even when none existed.  The 
problem often manifested itself using DBD::ODBC as:

    DBD::ODBC::st execute failed: [unixODBC][FreeTDS][SQL Server]
    Invalid cursor state (SQL-24000)(DBD: st_execute/SQLRowCount err=-1)
    	at /usr/bin/dbtransfer.pl line 336.

2.  SQLTransact() and SQLEndTran() would fail, saying the 
transaction couldn't be committed.  This problem was seen with unixODBC, 
and the good folks maintaining unixODBC offered a patch, which we modified
and applied.  

The above problems are corrected in 0.62.2.  

Known behavior: SQLFetch().  When a stored procedure returns 
a result set *and* executes subsequent queries, errors from the ensuing 
queries will not be reported.  SQLFetch() returns SUCCEED.  
We hope to address this in 0.63.  

Other issues
------------

*  Several VMS-related build issues were fixed.  
*  A few alignment problems in libtds were fixed.
*  Two buffer overflow conditions were addressed.  

                   =======================================

README for FreeTDS 0.62.1
Saturday, 14 January 2004

The 0.62 release included one late change that had not been thoroughly tested. 
This 0.62.1 release corrects that error.  

                   =======================================

README for FreeTDS 0.62  
Saturday, 10 January 2004

* to build FreeTDS read the file INSTALL,
* see also the FreeTDS Users Guide,
  http://www.freetds.org/userguide/

FreeTDS is a free (open source) implementation of Sybase's db-lib,
ct-lib, and ODBC libraries. FreeTDS builds and runs on every flavor of
unix-like systems we've heard of, as well as Win32 (with or without
Cygwin), VMS, and Mac OS X.  Failure to build on your system is probably
considered a bug.  It has C language bindings, and works also with Perl
and PHP, among others.  

FreeTDS is licensed under the GNU LGPL license. See COPYING.LIB for
details.  

Other files you might want to peruse:

AUTHORS		Who's involved
BUGS		Some things we fixed, or think we did
ChangeLog	Detailed list of changes
NEWS		Summary of feature changes and fixes
README		This file
TODO		The roadmap, such as it is

Also, doc/api_status.txt shows which functions are implemented.  

************************************
** Warning regarding Sybase 12.5! **
************************************

Do Not Use TDS version 4.2 to connect to Sybase 12.5. Please!  

While we don't like to put the bad news first, neither do we want you to
hurt your server.  We know that our implementation of TDS 4.2 gives
Sybase 12.5 a bad case of heartburn.  In short: it crashes the server.  

We don't know what it is about our version of TDS 4.2 that Sybase 12.5
doesn't like, and we'd like to figure it out eventually.  But in the
meanwhile, until we can find the problem and fix it, please don't use
that combination.  Unless you want to help us test it, that is.  

FreeTDS 0.62 works fine with Sybase 12.5 if you use TDS version 5.0.  

If you are using Sybase 12.5 and anything above is not clear to you,
please see the User Guide.  If it is still not clear after that, please
write to the FreeTDS mailing list.  We'd rather answer your questions
while your server is still running.  

Thank you.  We return now to your regularly scheduled README, already in
progress. 

Threadsafe by default
=====================

FreeTDS detects the presence of threadsafe functions on your system, and
attempts to use them if found.  This is new behavior.  If your compilation
fails, try configure's --disable-threadsafe option.  

iconv by default
================

FreeTDS detects the presence of libiconv on your system, and attempts to
use it if found.  If your compilation fails, try configure's
--disable-libiconv option.  This option restricts FreeTDS to using its
built-in character set conversion feature.  

FreeTDS includes its own minimal built-in libiconv, capable of converting
among ISO 8859-1, UCS-2, and UTF-8.  This is sufficient for many purposes,
including all languages that use the Roman alphabet.

We claim to support any client character set that does not embed binary
zeros in the data.  In particular, we believe we can support any UTF-8
client, and we know we *cannot* support a UCS-2 client.  Note, these are
client encodings we're referring to.  To the best of our knowledge, we
support all server encodings.  


ODBC by golly
=============

FreeTDS detects the presence of ODBC headers on your system, and compiles
the ODBC driver if found.  This is new behavior.  You do not need a driver
manager (although they're supported); the headers themselves are enough.  

MAC OS X comes with an ODBC installation that seems not to be well
documented or very functional.  Nevertheless, configure will detect it and
attempt to build the ODBC driver.  That will probably fail.  Use
configure's --disable-odbc to defeat.  Refer to the User Guide for
instructions on telling configure where your good ODBC headers are.  

The ODBC specification has some flaws regarding 64-bit systems.  

FreeTDS has been carefully tested with unixODBC.  Use unixODBC-2.2.6, not
unixODBC-2.2.7!  Success has also been reported with version 2.2.3;
version 2.0.x does not close transactions quite correctly.  

Much improved ODBC and ct-lib
=============================

These two libararies saw the most improvements in this release.   Here's
a comparison of completed functions, by library and version:

 library         nFunctions  v61         v62        
 --------------- ----------- ----------- -----------
 ctlib                    90          33          37
 dblib                   254         117         118
 odbc                     74          36          63

ct-lib is somewhat under-represented, in that ct-lib functions tend to
take a great many options, not all of which FreeTDS implements. 
Implementation of cursors and dynamic SQL in ct-lib required many options
in only a few functions.  

As you can see, ODBC is no longer an immature driver.  Here is a list of
functions mentioned in the ChangeLog for this release:

SQL(Driver)Connect	SQLGetStmtAttr
SQLBindParam		SQLGetStmtOption
SQLCloseCursor		SQLMoreResults
SQLColAttribute 	SQLNativeSql
SQLColumnPrivileges	SQLParamOptions
SQLColumns		SQLPrepare
SQLCopyDesc		SQLPrimaryKeys
SQLDriverConnect	SQLProcedureColumns
SQLEndTran		SQLProcedures
SQLError		SQLPutData
SQLExecDirect		SQLRowCount
SQLExecute		SQLSetCursorName
SQLFetchScroll		SQLSetDescField
SQLForeignKeys		SQLSetDescRec
SQLGetConnectAttr	SQLSetParam
SQLGetCursorName	SQLSetStmtAttr
SQLGetData		SQLSpecialColumns
SQLGetDescField 	SQLStatistics
SQLGetDescRec		SQLTablePrivileges
SQLGetEnvAttr		SQLTables
SQLGetInfo

One of the more popular uses of ct-lib is with Perl, in DBD::Sybase.  This
version works with DBD::Sybase 0.95 and later; we recommend at least
version 1.01.  

Unfortunately, placeholder support in FreeTDS is not yet sufficient for
use with DBD::Sybase. 

Location of installed files
===========================

FreeTDS by default installs itself in the /usr/local tree.  Prior to
0.60, FreeTDS installed into /usr/local/freetds.  If you wish to preserve
that behavior, build 0.62 with your prefix set to the old location. 
Example: ./configure --prefix=/usr/local/freetds/

If you have a version older than 0.60 installed, and want to "get with
the program" (use the new default locations), you will want to be sure
that the old configuration files are preserved, and the old binaries are
removed.  To do that, follow these steps:

1) move your configuration files to the new location. Example:
	cp /usr/local/freetds/etc/*.conf /usr/local/etc/

2) remove your old installation
	rm -fr /usr/local/freetds

3) if you have modified your /etc/ld.so.conf file to include 
/usr/local/freetds/lib, remove this and rerun "ldconfig"

4) if you have modified startup scripts for apache or similar
applications  to include /usr/local/freetds/lib in the LD_LIBRARY_PATH,
be sure to  remove them now.

Once you have installed FreeTDS and taken these steps, your new
installation should work at least as well as your old one.  You may wish
to try out "tsql" to test things.  See "man tsql" (!) for details.  

Documentation
=============

A User Guide, in sgml and html form, is included in this distribution. 
Also included is a reference manual, generated in HTML with Doxygen. 
"make install" installs the HTML documentation, by default to
/usr/local/share/doc/freetds-0.62.  


Note to Users
-------------

Submissions of test programs (self-contained programs that demonstrate
functionality or problems) are greatly appreciated.  They should
create any tables needed (since we obviously don't have access to your
database) and populate them.  Unit tests for any of the libraries
is appreciated

Notes to Developers
-------------------

The code is split into several pieces.

1) tds directory is the wire level stuff, it should be independent of
   the library using it, this will allow db-lib, ct-lib, and ODBC to
   sit on top.

2) db-lib directory. This is the actual db-lib code which runs on top of
   tds.

3) ct-lib directory. This is the ct-lib code which runs on top of tds. 

4) server directory. This will be a set of server routines basically
   to impersonate a dataserver, functions like send_login_ack() etc...

5) odbc directory. ODBC implementation over tds.  Uses iODBC or
   unixODBC as a driver manager.  You need to have one of those if you
   are using the ODBC CLI.

6) unittests directories. Test harness code for ct-lib, db-lib, ODBC and
   libtds.

6) samples directories. Sample code for getting started with Perl,
   PHP, etc...

7) pool directory. A connection pooling server for TDS.  Useful if you
   have a connection limited license.  Needs some hacking to get
   configured but is quite stable once configured correctly. Contact
   the list if interested in how to use it.

Please look at doc/getting_started.txt for a description of what is
going on in the code.

Side note: Brian, as many free software authors, appreciates postcards
from all over. So if you live someplace neat (read: not Michigan) and
want to send one, email him (brian@bruns.org) for his current snail mail
address.

$Id: README,v 1.8.4.7 2004/06/13 22:52:01 jklowden Exp $

